Overview
The Content Studio Subscription Service gives the web site author the possibility
to create powerful text or html based newsletters that automatically are sent out
to subscribers according to a specific schedule.
By using a number of new Server Controls it is easy to build web pages where visitors
can subscribe and unsubscribe to your newsletters or view their subscriptions.
Each type of subscription (ex. newsletters or price information)
are located in their own categories that can be enabled or disabled by an administrator.
When correctly set up, every newly created and published document will be sent out
to all of the subscribers according to the subscription schedule. When a document
has been sent out it will not be sent out again (risk for spam server) unless an
administrator forces the document to be re-sent. Additionally, if there are documents
in the category when it is set up for subscription, none of the existing documents
will be sent out either.
Technical details
In Content Studio 5.2 and later versions the Subscription Service are implemented as an addition to the regular Event Actions subsystem. Five new events have been added to support this.
- OnDocumentPublish
- This event occurs when a document is published. This event is triggered synchronously when a document is published directly. However if the document is scheduled to be published later in time; this event is triggered asynchronously in the background when the Service Manager discovers that the document has been published recently.
- OnDocumentArchive
- This event is similar to the OnDocumentPublish event but it occurs when a document has been archived; i.e. its archive date has been reached.
- OnDocumentUnpublish
- This event is similar to the OnDocumentPublish event but it occurs when a document is no longer published but not archived; i.e. its publish date date has been set to a future time or the document has been set to be no longer published.
- OnDocumentSubscription
- Occurs when the Service Manager has discovered that a document is about to be sent out for subscription. When this event a new job is added that will trigger the event handler that actually sends the document to its subscribers.
- OnTestDocumentTestSubscription
- Occurs when an administrator tests the subscription functionality of a specific category and a specific document. This event adds a new job for the Service Manager and is carried out by the event handler. on event handler this event might not be implemented by that event handler.
The actual mail sending operation is implemented in a regular event actions asynchronous event handler. Such an event handler is included in Content Studio and will meet the needs of most users. When the Service Manager discovers a subscription job, it calls this implementation to actually carry out the mail sending operation.
Administrating subscriptions from the administrative interface
From the Content Studio administrative interface you enable subscription on a specific category by opening the properties dialog on a category and navigating to the new Subscription tab.
Activation subscriptions
By checking the Activated checkbox in the upper right corner of this dialog the category is set up for subscription. In order to be able to activate subscription for a category or change any subscription related properties the caller must have WriteContainer permission for that category, a permission normally given only to developers and administrators. Before you can save your data you must also set other important properties necessary for the subscriptions to work.
General properties
The upper section of the dialog contains some general properties:
- Web site address
- Specifies the address that the even handler should use when it finds the document that should be transformed to a mail message and sent out to the subscribers. This value is one of the url:s specified by the site administrator in the SiteURL and MultiHomedSiteURL web site wide settings. Normally there is only one alternative here that is pre-set by the system.
- Presentation template
- Specifies the presentation template to use when the handler generates the mail message from the document being sent out. This is relevant for EPT-documents only and the default value --- Auto --- indicates that the default presentation template should be used or that presentation templates are not relevant for this category (i.e. not an EPT category).
- Sender
- This is the mail address that will be used as sender of all subscription mail being sent out. Most mail (SMPT) servers does not accept mails without a sender.
- Custom event handler
-
Specifies a custom implementation of the
ICSAsyncEventHandler interface that will be called by the Service Manager when mails are sent out. A custom event handler might be necessary to use if the built in implementation does not meet the requirements. These event handlers are regular .NET assemblies that implements theICSAsyncEventHandler interface, compiled as .DLL and are installed in the same directory as Content Studio server, CSServiceHost.exe or installed in the Global Assembly Cache (GAC).
The value of this property specifies the programmatic name of your event handler and can be written in several ways where the simplest form isNamespace.Class, Assembly name
The complete format looks like:Namespace.Class, Assembly name, Version=value, Culture=value, PublicKeyToken=value
- Examples
- The first example is as simple as it gets where only the full name and the assembly name are given. The assembly name is normally the same as the name of the dll file minus the .dll extension.
-
MyEventHandlers.OnDocumentSubscription, MyEventHandlers
- The second example is more specific an specifies that the event handler has been given a strong name and we also needs a specific version of the assembly to be loaded with a specific culture. This advanced type info is needed when your event handler assembly has been registered in the global assembly cache (GAC).
-
MyEventHandlers.OnDocumentSubscription, MyEventHandlers, Culture=neutral, Version=1.0.0.0, PublicKeyToken=feea6d4abcd740d9
- Timeout
- When the event handler implements time out functionality this value can be the time (in seconds) that a mail sending job may take before interrupted and considered an error by the Service Manager. The default value 0 (zero) should indicates no time out value. The current implementation of the built in event handler does not implement time outs and in this case; the value should always be zero.
Viewing subscribers
By hitting the "Subscribers" link you can view a list of all subscribers of the category. This list supports paging and displays both activated and not activated subscribers and from this list an administrator can add new subscribers by either hitting the "New subscriber" button or simply right-click somewhere in the list. By default new subscribers are not activated by default, which indicates by the icon with the stop sign. The administrator can easily activate or deactivate a single subscriber by just right-click on a subscriber and select the appropriate command in the context menu that appears. Deleting subscribers is done in exactly the same way.
Sending test messages
The Test send functionality is available for activated subscriptions only and displays the Test send dialog
From this dialog you can select any of the documents in the category and enter the address of one receiver. When you close the dialog by pressing the Send button Content Studio informs you that a test mail job has been created. Provided that the event handler supports sending test mails (the built in default provider support this) the mail is sent as soon as the Service Manager finds the job. Since this procedure is carried out in the same way as the regular send operations you can test that the whole chain is working.
Working with the schedule
The schedule part of the main dialog is used to specify when mail messages should be sent out to subscribers but you can also specify that no schedule should be used. It that case any new published document will be sent out to subscribers within just a few minutes or as long that it takes for the Service Manager and the mail server to send them out. The subscription administrative interface only supports one schedule but within this schedule you can specify as many occurrences you like during the day and you can specify any combination of weekdays. However, for practical reasons, most users find that one or two deliveries during work days are sufficient. For example you might want to send mail when the mail server is not busy with regular traffic; in this case 03:00 (03.00 AM) might be a good option.
Advanced settings
The advanced settings can be reached by hitting the "Advanced properties" dialog that displays the new Dynamic property editor.
The advanced properties are used to send information to the implementation of the subscription event handler. The built in event handler (which can be replaced by a third-party implementation) uses a number of settings related to Html mail rendering, logging and mail server settings. A brief summary of these properties are listed in the table below.
Setting name | Value | Description |
---|---|---|
Optional setting that specifies if and what logger to use. (Used by the built in handler and handlers that inherits the SubscriptionEventHandlerBase) | ||
ContentStudio.ServiceManager.Logging.ISysLogWriter |
A moniker (ex. "Mynamespace.Logging, MySyslogLogger" to an implementation of the
|
The built in implementation of the event handler will log all of its events to the implementation of this interface. To use the built in file logger this value should be ContentStudio.ServiceManager.Logging.FileLogger, CSEventhandlers. If this setting is omitted or has an empty value no logging is performed. If you specify the default logger you should set the ContentStudio.ServiceManager.Logging.FileLogger.Directory and ContentStudio.ServiceManager.Logging.FileLogger.FileName as well. If this settings is empty or omitted no logger is used. |
Optional settings that configures the built in file logger ContentStudio.ServiceManager.Logging.FileLogger | ||
ContentStudio.ServiceManager.Logging.FileLogger.Directory | The full path to the directory (ex. C:\temp\logging) on the server where the default file logger should save its log files. | Used only if ContentStudio.ServiceManager.Logging.ISysLogWriter is specified. If not specified and the default file logger is specified the logger writes to the temp directory known to the Service Manager runtime account (i.e. NT Authority\Network Service). Do not forget to check that the Service Manager runtime account (i.e. NT Authority\Network Service) has permission to write to this directory. |
ContentStudio.ServiceManager.Logging.FileLogger.FileName | The name of the log file that the default file logger should use. |
If a file name is specified (ex MyLog.log) the logger will append data to this file
rather that overwrite the current content. If this setting is omitted a filename based on the current data and time is generated. |
Optional settings that specifies how Content Studio documents are transformed into Html mail messages. (Used by the built in handler) | ||
MultipartMailMessage.MailFormatSettings |
A comma separated list of the members in the
|
This setting regulates how Content Studio generates Html mail messages. See the
|
Optional settings that specifies settings for the mail server used. (Used by the built in handler) | ||
System.Net.Mail.SmtpClient.DeliveryMethod |
One of the members in the
|
Defines how the mail service sends the mails. The default value is Network and if Pickup is specified System.Net.Mail.SmtpClient.PickupDirectoryLocation must be specified as well. |
System.Net.Mail.SmtpClient.PickupDirectoryLocation | The directory on the server where the mail server fetches mails to be sent. | Should only be specified if System.Net.Mail.SmtpClient.DeliveryMethod is Pickup |
System.Net.Mail.SmtpClient.Port | A SMTP port number to use. Default value is 25 | Only used if System.Net.Mail.SmtpClient.DeliveryMethod is Network and the default port 25 cannot be used for some reason. |
Optional settings that controls how mails are sent out. (Used by the built in handler) | ||
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.RecipientFailRetryLimit | Integer, default value is 5 | Specifies the maximum number of times that the event handler should try to resend a message to a client when there is a non-fatal, temporary error. |
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.SmtpFailureLimit | Integer, default value is 2 | Specifies the number of SMTP failures that is accepted before the handler stops and reports an error. |
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.FailureRetryInterval | Integer, default value is 5000 (milliseconds) | Specifies the interval (in milliseconds) that the handler should wait before it tries to resend a failed message. |
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.MaxNumberOfAllowedFailedRecipients | Integer, default value is 100 | Specifies the max number of allowed failed recipients allowed before the event handler reports an error and stops. |
Properties for outgoing mails
- Server name or IP:
- Specifies the name or IP address of the SMPT (mail) server that the event handler uses when it sends out the mail messages to the subscribers.
- Authentication method:
-
Specifies whether and how the event handler authenticates to the mail server. Not
all mail server requires authentication. There are three different methods supported.
- Anonymous
- Mail messages are sent anonymously and no authentication is required. This is the default value. Some mail servers might allow non-authenticated clients to send messages locally but prohibits relaying (outside the local network) if not authenticated. For this reason always test subscriptions both with external and internal messages.
- Windows
- Messages are sent using the Service Manager's own credentials i.e. NT AUTHORITY\Network Service). Not all mail servers supports this authentication method but is supported with Microsoft Exchange. Windows authentication cannot be used between server (i.e. the mail server is located on a remote computer) unless both computers (Web server and mail server) are members of the same Active Directory. Windows authentication (also known as integrated authentication) is very safe and robust since no passwords are stored and transmitted over the network.
- Basic
- This is the standard method of authentication supported by most mail servers. Use this method as a last resort only since credentials are sent in clear text to the mail server. The credentials are stored encrypted in the database and by default only the Service Manager (i.e. sessions in Content Studio that has the ServiceQueueAdmin global group right set) can read this information in clear text. Also, this information is readable only on the web server that stored them in the first place. If Content Studio is moved or restored to another server all subscription credentials are lost and must be entered again. A future version of Content Studio might include a tool that can copy and restore these credentials. Also Basic authentication is not supported if Content Studio is set up to run as a web farm and mail credentials are saved or read on different servers.
- User data:
- Only available when Basic authentication is used. By click this link a dialog is displayed where one can enter user credentials for Basic authentication. If specified the username and a symbolic password is displayed in the textboxes below this link. The password is not stored somewhere in the Html code, what is shown is just a dummy value to give the impression of a password.
Viewing subscription properties for a document
This new dialog displays the subscription related properties for a document. You can reach this dialog by right-clicking a document in the document list in the Content Studio administrative interface and select the Properties option. This displays the document properties dialog which has a button "Subscription properties" that brings this dialog up.
In this dialog you can determine whether subscription is enabled for the document's category and the current subscription status for the document. The following status values are available for any document:
- Will not be sent or already sent
- This is the status of document that are not subject to subscription. This is true also for documents that existed in a category before subscription was enabled on that category. Also this is the status given to all existing documents in a category when subscription is turned off.
- Will be sent after publishing
-
The document is not published yet but will be scheduled for subscription as soon
it has been published. This can occur when:
- the document is approved and published
- an approved document that is not yet published (its publish date is greater than the current date or it has not yet been marked published).
- Will be sent according to the schedule
-
The document is published and will soon be scheduled. No job has yet been created
for the document.
- the document has been saved but not yet approved and published.
- an approved document that is not yet published (its publish date is greater than the current date or it has not yet been marked published).
- Queued or in progress
- A job has been created and will be executed when scheduled - or the job is currently executing.
- Sent
- The document has been sent to the subscribers and will normally not be sent again.
- Invalid or an error has occurred
- This status simply indicates that data could not be read properly.
Changing status of a document
By changing subscription status of a document you prevent a document from being sent or force a document to be sent out
- Stop send
- You can stop a document from being sent as long as it has not been scheduled or is in progress. If you stop a document from being sent its status will be set to Will not be sent or already sent and will not be sent out automatically again.
- Force resend
- Forces a document that is not meant to be sent out to be sent according to the schedule.
- Send when published
-
Enables the document to be sent out as soon it is re-published. Such a document
is normally never sent out again. A document is re-published if it
- was not marked as published (with-drawn) and later marked published.
- An archived document's archive date is changed so it is published again.
- The publish date of a document was been changed so that it is went un-published. The document is the re-published when the new publish date has been reached.
Developing subscription documents
Any subscription system is worthless unless visitors can subscribe to your newsletters. Even though an administrator can manually add and remove subscribers this is, of course, very unpractical. For this reason the best way is to create a number of web pages that let the visitor accomplish these tasks. These pages can be developed from scratch by a skilful programmer using the Subscription API but it is much easier to use one or more of the server controls distributed with the product.
Any subscription system is useless unless visitors can subscribe to your newsletters. An administrator can manually add and remove subscribers but this is, of course, very unpractical. The best way to let visitors subscribe to your newsletters is to create a number of web pages that let the visitor accomplish this. These pages can be developed from scratch by a skilful programmer using the Subscription API but it is much easier to use the server controls distributed with the product.
- SubscriptionManager
- This control displays a list of categories a visitor can subscribe on. The subscriptions can either be activated directly or via a confirmation mail message. If you choose to require activation mails you must also develop a confirmation mail message document and a activation document. Activation mails using the built-in functionality requires that the SMTP settings are correctly configured. For more information about this control and how to configure it see the SubscriptionManager control documentation.
- SubscriptionAction
- This control when placed on a document performs an actions on a specific subscribers subscription when the page is loaded. These actions are; remove, activate and deactivate the subscription. The subscription is identified by a very long and unique identifier
- SubscriptionRemover
- This control displays a list of all categories that a specific user has subscriber to. A visitor can check all subscriptions to remove and have them removed. The control supports sending a confirmation mail message containing a link to a page that contains the SubscriptionAction control set to remove passed in subscriptions. Confirmation mails using the built-in functionality requires that the SMTP settings are correctly configured. For more information about this control and how to configure it see the SubscriptionRemover control documentation.
- SubscriptionMarker
- This control us primarily used on pages used as regular subscription mail or confirmation mail messages. The control inserts a marker that will be replaced with the actual user data when the confirmation mail is sent out.
- SubscriptionLink
- This control inserts a link with subscription identifier data in regular subscription mail or a confirmation mail message. The generated link contains one or more query string elements needed by the SubscriptionAction control. When the mail is sent out the mail handler inserts the correct link with the unique subscription data for the subscriber.
- SubscribableCategoryCheckBox
- This control displays a checkbox representing a subscribable category. When added to a page, the developer can select the category to use from a list of categories that are enabled for subscription. The SubscriptionManage and SubscriptionRemover controls make extensively use of this control. Use this control when you develop your own subscription applications.